package com.zenithmind.document.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.service.IService;
import com.zenithmind.document.pojo.domain.DocumentAccessLog;
import com.zenithmind.document.pojo.dto.DocumentAccessLogCreateDTO;
import com.zenithmind.document.pojo.query.DocumentAccessLogQueryDTO;
import com.zenithmind.document.pojo.vo.DocumentAccessLogVO;

import java.util.List;

/**
 * 文档访问日志服务接口
 * 遵循接口隔离原则：专注于访问日志管理功能
 * 遵循单一职责原则：只负责访问日志相关操作
 * 
 * @author ZenithMind Team
 * @since 2025-01-09
 */
public interface DocumentAccessLogService extends IService<DocumentAccessLog> {

    /**
     * 记录文档访问
     * 
     * @param createDTO 访问记录信息
     * @return 访问记录
     */
    DocumentAccessLogVO recordAccess(DocumentAccessLogCreateDTO createDTO);

    /**
     * 记录文档查看
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @param userAgent 用户代理
     * @param ipAddress IP地址
     * @return 访问记录
     */
    DocumentAccessLogVO recordView(String documentId, String userId, String userAgent, String ipAddress);

    /**
     * 记录文档下载
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @param userAgent 用户代理
     * @param ipAddress IP地址
     * @return 访问记录
     */
    DocumentAccessLogVO recordDownload(String documentId, String userId, String userAgent, String ipAddress);

    /**
     * 记录文档分享
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @param shareType 分享类型
     * @param userAgent 用户代理
     * @param ipAddress IP地址
     * @return 访问记录
     */
    DocumentAccessLogVO recordShare(String documentId, String userId, String shareType, String userAgent, String ipAddress);

    /**
     * 分页查询访问日志
     * 
     * @param queryDTO 查询条件
     * @return 分页结果
     */
    IPage<DocumentAccessLogVO> getAccessLogPage(DocumentAccessLogQueryDTO queryDTO);

    /**
     * 获取文档访问日志
     * 
     * @param documentId 文档ID
     * @param limit 限制数量
     * @return 访问日志列表
     */
    List<DocumentAccessLogVO> getDocumentAccessLogs(String documentId, Integer limit);

    /**
     * 获取用户访问日志
     * 
     * @param userId 用户ID
     * @param limit 限制数量
     * @return 访问日志列表
     */
    List<DocumentAccessLogVO> getUserAccessLogs(String userId, Integer limit);

    /**
     * 获取访问统计
     * 
     * @param documentId 文档ID
     * @param days 统计天数
     * @return 统计信息
     */
    Object getAccessStatistics(String documentId, Integer days);

    /**
     * 获取热门访问文档
     * 
     * @param days 统计天数
     * @param limit 限制数量
     * @return 文档列表
     */
    List<Object> getHotAccessDocuments(Integer days, Integer limit);

    /**
     * 获取访问趋势
     * 
     * @param documentId 文档ID
     * @param days 统计天数
     * @return 趋势数据
     */
    List<Object> getAccessTrend(String documentId, Integer days);

    /**
     * 获取用户访问行为分析
     * 
     * @param userId 用户ID
     * @param days 统计天数
     * @return 行为分析数据
     */
    Object getUserAccessBehavior(String userId, Integer days);

    /**
     * 获取IP访问统计
     * 
     * @param days 统计天数
     * @param limit 限制数量
     * @return IP统计数据
     */
    List<Object> getIpAccessStatistics(Integer days, Integer limit);

    /**
     * 获取设备访问统计
     * 
     * @param days 统计天数
     * @return 设备统计数据
     */
    List<Object> getDeviceAccessStatistics(Integer days);

    /**
     * 获取浏览器访问统计
     * 
     * @param days 统计天数
     * @return 浏览器统计数据
     */
    List<Object> getBrowserAccessStatistics(Integer days);

    /**
     * 获取访问时间分布
     * 
     * @param days 统计天数
     * @return 时间分布数据
     */
    List<Object> getAccessTimeDistribution(Integer days);

    /**
     * 检测异常访问
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @param ipAddress IP地址
     * @return 是否异常
     */
    Boolean detectAbnormalAccess(String documentId, String userId, String ipAddress);

    /**
     * 清理过期访问日志
     * 
     * @param retentionDays 保留天数
     * @return 清理数量
     */
    Integer cleanupExpiredLogs(Integer retentionDays);

    /**
     * 导出访问日志
     * 
     * @param queryDTO 查询条件
     * @return 导出数据
     */
    Object exportAccessLogs(DocumentAccessLogQueryDTO queryDTO);

    /**
     * 获取实时访问统计
     * 
     * @return 实时统计数据
     */
    Object getRealTimeAccessStatistics();

    /**
     * 获取访问地域分布
     * 
     * @param days 统计天数
     * @return 地域分布数据
     */
    List<Object> getAccessLocationDistribution(Integer days);

    /**
     * 获取访问来源统计
     * 
     * @param days 统计天数
     * @param limit 限制数量
     * @return 来源统计数据
     */
    List<Object> getAccessSourceStatistics(Integer days, Integer limit);

    /**
     * 获取访问路径分析
     * 
     * @param userId 用户ID
     * @param days 统计天数
     * @return 路径分析数据
     */
    List<Object> getAccessPathAnalysis(String userId, Integer days);

    /**
     * 获取访问会话统计
     * 
     * @param days 统计天数
     * @return 会话统计数据
     */
    Object getAccessSessionStatistics(Integer days);

    /**
     * 批量记录访问
     * 
     * @param accessLogs 访问记录列表
     * @return 成功数量
     */
    Integer batchRecordAccess(List<DocumentAccessLogCreateDTO> accessLogs);

    /**
     * 同步访问统计
     * 
     * @return 是否成功
     */
    Boolean syncAccessStatistics();
}
